home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Tech Arsenal 1
/
Tech Arsenal (Arsenal Computer).ISO
/
tek-01
/
xlib04.zip
/
XLIBREF2.DOC
< prev
next >
Wrap
Text File
|
1992-11-10
|
26KB
|
767 lines
PART 2 of 2
-----------------------------------------------------------------------------
********* XLIB - Mode X graphics library ****************
********* ****************
********* Written By Themie Gouthas ****************
********* ****************
********* egg@dstos3.dsto.gov.au ****************
********* teg@bart.dsto.gov.au ****************
Some of the code in this library has been contributed by :
Matthew MacKenzie - matm@eng.umd.edu
Notes:
References to my employer have been removed as this library is my
own intellectual property, developed solely in my own time.
I informally reserve all rights to the code in XLIB.
-----------------------------------------------------------------------------
--------------------------------------------------------------------------
MODULE XCLIPPBM note: VERY SIMILAR to XPBMCLIP
This module implements clipping pbm puts that are pixel
alignment independent (and thus a little slower)
--------------------------------------------------------------------------
XCLIPPBM:
Blits and Pieces
by Matthew MacKenzie
The XCLIPPBM module contains clipping versions of two of the three routines
in the XPBITMAP module:
o x_clip_pbm transfers a planar bitmap to the screen, clipping off any
part outside a bounding box.
o x_clip_masked_pbm does the same thing, but transfers only nonzero
pixels.
The planar bitmap format is described elsewhere. Here we will look at
the clipping itself, since it is the only distinguishing feature of this
module.
The bounding box is made up of four integers, TopBound, BottomBound,
LeftBound, and RightBound. Unlike most global variables in Xlib, these are
meant to be written to. In fact, they start out uninitialized. Be sure to
set them before you try plotting any clipped bitmaps.
Note that these are not the same variables which are used in the other
clipping modules in Xlib. This is because the two systems are incompatible:
the other modules clip horizontally to columns while this one clips to
pixels. As you might have guessed, those functions and these were developed
in different hemispheres of the planet...
If it's any consolation, this does give you two independent
bounding boxes to futz with, should the mood visit you.
Bitmaps cannot go outside the perimeter of the bounding box, but they
can overlap it. If TopBound equals BottomBound, for example, a horizontal
slice of a bitmap may still be plotted. It is safe to turn the box "inside
out" to make sure nothing will be plotted -- this is the first thing each
routine checks for.
To plot a bitmap, minus its zero pixels, minus anything outside the
bounding box:
x_clip_masked_pbm (int X, int Y, int ScreenOffs, char far * Bitmap);
The arguments are in the same order as those for x_put_masked_pbm in
the module XPBITMAP. The bounding box is relative to the given
ScreenOffs(et). This lets you perform page flipping without worrying about
what screen you are clipping to -- it's always the current screen. The
bitmap itself, of course, is not affected; clipping is performed on-the-
fly.
The third function in XPBITMAP, for which this module has no
equivalent, copies from video RAM to system RAM. The absence of such a
routine may seem at first like a disadvantage -- but this, like so many
things in this life, is an illusion. You can use the unclipped routine,
and clip the bitmap when you want to plot it back onto the screen.
ASM SOURCES
xclippbm.asm xclippbm.inc xlib.inc model.inc
C HEADER FILE
xclippbm.h
EXPORTED VARIABLES
TopBound - int
BottomBound - int
LeftBound - int
RightBound -int
EXPORTED FUNCTIONS
x_clip_pbm
----------
C Prototype: extern void x_clip_pbm (int X, int Y, int ScreenOffs, char
far * Bitmap);
Copies a planar bitmap from SRAM to VRAM, with clipping */
x_clip_masked_pbm
-----------------
C Prototype: extern void x_clip_masked_pbm (int X, int Y,
int ScreenOffs, char far * Bitmap);
Copies a planar bitmap from SRAM to VRAM, with clipping -- 0 bytes
in the bitmap are not copied.
--------------------------------------------------------------------------
MODULE XMOUSE
--------------------------------------------------------------------------
The XMOUSE module implements very basic mouse handling functions. The way
in which it operates is by installing an event handler function during
initialization which subsequently intercepts and processes mouse events and
automatically updates status variables such as mouse position and button
pressed status. It does not support the full functionality of:
SPLIT SCREENS
SCROLLED WINDOWS
VIRTUAL WINDOWS
This was done to primarily prevent unecessary impedences to performance,
since the mouse handler function has the potential to degrade performance.
It also saves me alot of coding which I was too lazy to do.
Programs communicate with the mouse driver as with other devices, through
an interrupt vector namely 33h. On generating an interrupt, the mouse driver
expects a function number in AX and possibly other parameters in other
registers and returns information via the registers. A brief description
of the mouse functions follows:
--------------------------------------
MS Mouse Driver Functions
Mouse Initialization 0
Show Cursor 1
Hide Cursor 2
Get Mouse Position & Button Status 3
Set Mouse Cursor Position 4
Get Button Press Information 5
Get Button Release Information 6
Set Min/Max Horizontal Position 7
Set Min/Max Vertical Position 8
Define Graphics Cursor Block 9
Define Text Cursor 10
Read Mouse Motion Counters 11
Define Event Handler 12
Light Pen Emulation Mode ON 13
Light Pen Emulation Mode OFF 14
Set Mouse Mickey/Pixel Ratio 15
Conditional Hide Cursor 16
Set Double-Speed Threshold 19
--------------------------------------
In practice only afew of these functions are used and even fewer when the
mouse status is monitored by an event handler function such as is used in
this module.
The most important thing to note when using the mouse module is that the
mouse event handler must be removed before exiting the program. It is a good
idea to have an exit function (see the C "atexit" function) and include the
line "x_mouse_remove();" along with any other pre-exit cleanup code.
See also: XDETECT for mouse detection.
ASM SOURCES
xmouse.asm xlib.inc model.inc
C HEADER FILE
xmouse.h
EXPORTED VARIABLES
MouseInstalled - WORD - Indicates whether mouse handler installed
MouseHidden - WORD - Indicates whether mouse cursor is hidden
MouseButtonStatus - WORD - Holds the mouse button status
MouseX - WORD - Current X position of mouse cursor
MouseY - WORD - Current Y position of mouse cursor
MouseFrozen - WORD - Disallows position updates if TRUE
MouseColor - BYTE - The mouse cursors colour
EXPORTED FUNCTIONS
x_mouse_init
------------
C Prototype: int x_mouse_init()
Initialize the mouse driver functions and install the mouse event handler
function. This is the first function you must call before using any of the
mouse functions. This mouse code uses the fastest possible techniques to
save and restore mouse backgrounds and to draw the mouse cursor.
WARNING: This function uses and updates "NonVisual_Offset" to allocate
video ram for the saved mouse background.
LIMITATIONS: No clipping is supported horizontally for the mouse cursor
No validity checking is performed for NonVisual_Offs
**WARNING** You must Hide or at least Freeze the mouse cursor while drawing
using any of the other XLIB modules since the mouse handler may
modify vga register settings at any time. VGA register settings
are not preserved which will result in unpredictable drawing
behavior. If you know the drawing will occur away from the
mouse cursor set MouseFrozen to TRUE (1), do your drawing
then set it to FALSE (0). Alternatively call "x_hide_mouse",
perform your drawing and then call "x_show_mouse". Another
alternative is to disable interrupts while drawing but usually
drawing takes up alot of time and having interrupts disabled
for too long is not a good idea.
x_define_mouse_cursor
---------------------
C Prototype:
void x_define_mouse_cursor(char far *MouseDef, unsigned char MouseColor)
MouseDef - a pointer to 14 characters containing a bitmask for all the
cursor's rows.
MouseColor - The colour to use when drawing the mouse cursor.
Define a mouse cursor shape for use in subsequent cursor redraws. XMouse
has a hardwired mouse cursor size of 8 pixels across by 14 pixels down.
WARNING: This function assumes MouseDef points to 14 bytes.
Note: Bit order is in reverse. ie bit 7 represents pixel 0 ..
bit 0 represents pixel 7 in each "MouseDef" byte.
x_show_mouse
------------
C Prototype: void x_show_mouse()
Makes the cursor visible if it was previously hidden.
See Also: "x_hide_mouse".
x_hide_mouse
------------
C Prototype: void x_hide_mouse()
Makes the cursor hidden if it was previously visible.
See Also: "x_show_mouse".
x_remove_mouse
--------------
C Prototype: void x_remove_mouse()
Stop mouse event handling and remove the mouse handler.
NOTE: This function MUST be called before quitting the program if
a mouse handler has been installed
x_position_mouse
----------------
C Prototype void x_position_mouse(int x, int y)
Positions the mouse cursor at the specified location
x_update_mouse
--------------
C Prototype: void x_update_mouse()
Forces the mouse position to be updated and cursor to be redrawn.
Note: this function is useful when you have set "MouseFrozen" to true.
Allows the cursor position to be updated manually rather than
automatically by the installed handler.
--------------------------------------------------------------------------
MODULE XCIRCLE
--------------------------------------------------------------------------
XCIRCLE:
Wheel Have to See About That
by Matthew MacKenzie
The XCIRCLE module contains two functions, neither of which should be
a big mystery:
o x_circle, oddly enough, draws a circle.
o x_filled_circle does too, only the circle is filled (in some
libraries this is called a disc).
The word `circle' here refers to a round thing which is as many
pixels tall as across. It only looks like a circle in 320x240 mode --
the original mode X -- and in 376x282 mode.
In both functions, the circle is specified by the coordinates of the
upper-left-hand corner of the smallest box which holds it, and the
diameter. Some circle functions have you specify a center point;
this system is kind of odd because a circle with an even diameter does
not have a particular pixel for a center. Every circle, on the other
hand, has a box with an upper-left corner.
No bounds are checked. A diameter of zero will draw nothing, and
a negative diameter will blow your VGA board into hundreds of thousands
of tiny little smoldering fragments. Neither function supports clipping.
The calculation of the circle is based on an algorithm described
by Michael P. Lindner in a letter to the editor on page 8 of Dr. Dobb's
Journal #169 (October 1990). The algorithm has been rearranged to
allow drawing and moving the plots in the eight octants to be performed
in one step, so that each pixel does not have to be loaded into the CPU
twice. x_filled_circle does not take advantage of this optimization
because it handles different parts of each plot at different times.
ASM SOURCES
xcircle.asm xcircle.inc xlib.inc model.inc
C HEADER FILE
xcircle.h
EXPORTED FUNCTIONS
x_circle
--------
C Prototype: extern void x_circle (WORD Left, WORD Top, WORD Diameter,
WORD Color, WORD ScreenOffs);
Draws a circle with the given upper-left-hand corner and diameter,
which are given in pixels.
x_filled_circle
---------------
C Prototype: extern void x_filled_circle (WORD Left, WORD Top,
WORD Diameter, WORD Color, WORD ScreenOffs);
Draws a filled circle with the given upper-left-hand corner and
diameter.
--------------------------------------------------------------------------
MODULE XDETECT
--------------------------------------------------------------------------
This module implements a set of functions to detect the PC's hardware
configuration.
ASM SOURCES
xdetect.asm xdetect.inc model.inc
C HEADER FILE
xdetect.h
EXPORTED MACROS
I8086 0
I80186 1
I80286 2
I80386 3
NoGraphics 0
MDA 1
CGA 2
EGAMono 3
EGAColor 4
VGAMono 5
VGAColor 6
MCGAMono 7
MCGAColor 8
BUS_MOUSE 1
SERIAL_MOUSE 2
INPORT_MOUSE 3
PS2_MOUSE 4
HP_MOUSE 5
EXPORT VARIABLES
MouseButtonCount - WORD - The number of buttons on the detected mouse
MouseVersion - WORD - Mouse driver version (High byte = Major version
Low byte = minor version)
MouseType - BYTE - The mouse type
MouseIRQ - BYTE - The IRQ number used by the mouse driver
EXPORT FUNCTIONS
x_graphics_card
---------------
C Prototype: extern int x_graphics_card();
This function returns the type of graphics card installed. See defines
above.
x_processor
-----------
C Prototype: extern int x_processor();
This function returns the type of processor installed. A 486 registers
as a 386. See defines above.
x_coprocessor
-------------
C Prototype: extern int x_coprocessor();
This function returns 1 of a numeric co-processor is present, 0 if not.
The type is not detected but it's mnot really necessary as the processor
type usually determines the numeric coprocessor type
x_mousedriver
-------------
C Prototype: extern int x_mousedriver();
This function returns 1 of a mouse driver is installed, 0 otherwise.
If a mouse driver is detected the mouse related variable (above) are
set accordingly.
--------------------------------------------------------------------------
MODULE XFILEIO
--------------------------------------------------------------------------
Handle based file I/O functions.
See any good DOS programming reference for more information on int 21h
DOS services.
ASM SOURCES
xfileio.asm xfileio.inc model.inc
C HEADER FILE
xfileio.h
EXPORTED MACROS
file access modes
F_RDONLY
F_WRONLY
F_RDWR
seek codes
SEEK_START
SEEK_CURR
SEEK_END
file error value
FILE_ERR
EXPORT FUNCTIONS
f_open
------
C Prototype: extern int f_open(char * filename, char access);
Opens a file according to the access char:
F_RDONLY = read only - If doesnt exist return error
F_WRONLY = write only - If doesnt exist create it otherwise clear it
F_RDWR = read/write - If doesnt exist create it
Returns the file handle on success, FILE_ERR on failure
f_close
-------
C Prototype: extern int f_close(int handle);
Closes the file associated with the specified handle
Returns 0 on success, FILE_ERR on failure
f_read
------
C Prototype: extern int f_read(int handle, char far * buffer, int count);
Reads a block of count bytes from the file specified by the handle
into the buffer
Returns count on success, FILE_ERR on failure
f_write
-------
C Prototype: extern int f_write(int handle, char far * buffer, int count);
Writes a block of count bytes to the file specified by the handle
from the buffer
Returns count on success, FILE_ERR on failure
f_seek
------
C Prototype: extern long int f_seek(int handle, long int position,
char method_code)
Moves the file pointer according to the position and method code
Returns file pointer position on success, FILE_ERR on failure
f_filelength
------------
C Prototype:
extern long int f_filelength(int handle)
Returns the length of the file associated with the specified handle
Returns file length on success, FILE_ERR on failure
--------------------------------------------------------------------------
MODULE XRLETOOL
--------------------------------------------------------------------------
This module implements a number of functions comprising an RLE encoding
decoding system.
RLE stands for RUN LENGTH ENCODING. It is a quick simple data compression
scheme which is commonly used for image data compression or compression
of any data. Although not the most efficient system, it is fast, which is
why it is used in image storage systems like PCX. This implementation is
more efficient than the one used in PCX files because it uses 1 bit to
identify a Run Length byte as opposed to two in PCX files, but more on this
later.
This set of functions can be used to implement your own compressed image
file format or for example compress game mapse for various levels etc.
The uses are limited by your imagination.
I opted for trading off PCX RLE compatibility for the improved compression
efficiency.
Here is how the data is un-compressed to give an idea of its structure.
STEP 1 read a byte from the RLE compressed source buffer.
STEP 2 if has its high bit is set then the lower 7 bits represent the number
of times the next byte is to be repeated in the destination buffer.
if the count (lower 7 bits) is zero then
we have finished decoding goto STEP 5
else goto STEP 4
STEP 3 Read a data from the source buffer and copy it directly to the
destination buffer.
goto STEP 1
STEP 4 Read a data byte from the source buffer and copy it to the destination
buffer the number of times specified by step 2.
goto STEP 1
STEP 5 Stop, decoding done.
If the byte does not have the high bit set then the byte itself is transfered
to the destination buffer.
Data bytes that have the high bit already set and are unique in the input
stream are represented as a Run Length of 1 (ie 81 which includes high bit)
followed by the data byte.
If your original uncompressed data contains few consecutive bytes and most
have high bit set (ie have values > 127) then your so called
compressed data would require up to 2x the space of the uncompressed data,
so be aware that the compression ratio is extremely variable depending on the
type of data being compressed.
Apologies for this poor attempt at a description, but you can look up
RLE in any good text. Alternatively, any text that describes the PCX file
structure in any depth should have a section on RLE compression.
ASM SOURCES
xrletool.asm xrletool.inc model.inc
C HEADER FILE
xrletool.h
EXPORTED MACROS
EXPORT FUNCTIONS
x_buff_RLDecode
---------------
Expands an RLE compresses source buffer to a destination buffer.
returns the size of the resultant uncompressed data.
C PROTOTYPE:
extern unsigned int x_buff_RLDecode(char far * source_buff,
char far * dest_buff);
source_buff - The buffer to compress
dest_buff - The destination buffer
WARNING: buffers must be pre allocated.
x_buff_RLEncode
---------------
RLE Compresses a source buffer to a destination buffer and returns
the size of the resultant compressed data.
C PROTOTYPE:
extern unsigned int x_buff_RLEncode(char far * source_buff,
char far * dest_buff,unsigned int count);
source_buff - The buffer to compress
dest_buff - The destination buffer
count - The size of the source data in bytes
WARNING: buffers must be pre allocated.
x_buff_RLE_size
---------------
Returns the size the input data would compress to.
C PROTOTYPE:
extern unsigned int x_buff_RLE_size(char far * source_buff,
unsigned int count);
source_buff - The uncompressed data buffer
count - The size of the source data in bytes
x_file_RLEncode
---------------
RLE Compresses a source buffer to an output file returning
the size of the resultant compressed data or 0 if it fails.
C PROTOTYPE:
extern unsigned int x_file_RLEncode(int handle,
char far * source_buff,unsigned int count);
source_buff - The buffer to compress
handle - The file handler
count - The size of the source data in bytes
x_file_RLDecode
---------------
Expands an RLE compresses file to a destination RAM buffer.
returns the size of the resultant uncompressed data.
C PROTOTYPE:
extern unsigned int x_buff_RLDecode(int handle,
char far * dest_buff);
handle - Input file handle
dest_buff - The destination buffer
--------------------------------------------------------------------
REFERENCE SECTION
--------------------------------------------------------------------
REFERENCES
----------
In my opinion Doctor Dobbs Journal is the best reference text for
VGA Mode X graphics:
Issue 178 Jul 1991 : First reference to Mode X
Article Abstract : VGA's undocumented Mode X supports page flipping,
makes off screen memory available, has square pixels,
and increases performance by as muck as 4 times.
Issue 179 Aug 1991 : Continuation
Article Abstract : Michael discusses latches and VGA's undoccumented
Mode X.
Issue 181 Sep 1991 : Continuation
Article Abstract : Michael puts the moves on animation using VGA's 256
colors.
Issue 184 Oct 1991 : First of a continuing series covering 3-D animation
using VGA's Mode X. This series is still ongoing
(October 1992)
Article Abstract : Michael moves into 3-D animation, starting with basic
polygon fills and page flips.
WHAT IS MODE X ?
----------------
Mode X is a derrivative of the VGA's standard mode 13h (320x200 256 color).
It is a (family) of undocumented video modes that are created by tweaking
the VGA's registers. The beauty of mode X is that it offers several
benefits to the programmer:
- Multiple graphice pages where mode 13h doesn't allowing for page flipping
(also known as double buffering) and storage of images and data in
offscreen video memory
- A planar video ram organization which although more difficult to program,
allows the VGA's plane-oriented hardware to be used to process pixels in
parallel, improving performance by up to 4 times over mode 13h
See issue 178-179 of D.D.J. for a full description of VGA's Mode X.
WHAT IS A SPLIT SCREEN ?
------------------------
A split screen is a neat hardware feature offered by the EGA and VGA video
cards. A split screen is a mode of graphics operationin which the Hardware
splits the visual graphics screen horizontally and treats both halves as
individual screens each starting at different locations in video RAM.
The bottom half (which is usually referred to as the split screen) always
starts at address A000:0000 but the top half's starting address is user
definable.
The most common application of split screens in games is the status display
in scrolling games. Split screens make this sort of game simpler to program
because when the top half window is scrolled the programmer does not have to
worry about redrawing the bottom half.
WHAT IS DOUBLE BUFFERING ?
--------------------------
Double buffering (also known as page flipping) is the technique most often
used to do animation. it requires hardware that is capable of displaying
multiple graphics pages (or at least 2). Animation is achieved by drawing
an image in the non visible screen and then displaying the non visible
screen. Once the page has been flipped the process starts again. The next
frame of the animation is drawn on the non visible screen, the page is
flipped again etc.
WHAT IS MODE X ?
----------------
Mode X is a derrivative of the VGA's standard mode 13h (320x200 256 color).
It is a (family) of undocumented video modes that are created by tweaking
the VGA's registers. The beauty of mode X is that it offers several
benefits to the programmer:
- Multiple graphice pages where mode 13h doesn't allowing for page flipping
(also known as double buffering) and storage of images and data in
offscreen video memory
- A planar video ram organization which although more difficult to program,
allows the VGA's plane-oriented hardware to be used to process pixels in
parallel, improving performance by up to 4 times over mode 13h
Again see D.D.J. for an in depth discussion of animation using Mode X.
-----------------------------------------------------------------------